SoDA

Software Document Automation

Software documentation is traditionally done manually, usually with a publishing tool, or automatically using a document generator tied to a specific software-development tool. The manual method is flexible but labor intensive, especially on large projects. Conventional document generators eliminate tedious cut-and-paste operations, but sacrifice flexibility. SoDA(R) offers you the best of both worlds, giving you powerful automation and exceptional flexibility. SoDA is part of Rational's modern software-engineering solution, which comprises a set of software processes, products, and services that give you control of your software-development efforts and sharpen your competitive edge.

What is SoDA?

SoDA automates the production of software documentation, substantially reducing the effort required to produce software documentation. SoDA makes your software documentation more useful by improving its quality, consistency, and accessibility in all phases of the software-development lifecycle. SoDA can be customized to support any documentation standard. It can extract data from a variety of software-engineering tools. SoDA works with tools supporting any programming language.

Fundamental considerations in developing software documentation

Software developers in many industries produce software documentation, either for internal use or for customers as a deliverable. In some cases, software documentation is used to prove conformance to externally imposed safety, certification, or regulatory standards.

Analysis and design tools, programming environments, and testing tools are some of the many software-development tools used that contain information that can become part of software documentation. For example, the programming environment may contain information about the code that defines the names and number of sections in a document. Tools may also contain graphics and text that can be included in the documentation. The software-development tools, however, seldom contain all of the information necessary for the documentation. Explanations and other annotations usually must be added to the final documentation.

If you need to create software documentation automatically and flexibly while maintaining consistency with your software-development tools and processes, SoDA is your solution.

The SoDA solution

SoDA's unique capabilities let you extract information automatically from your software-development tools and let you enter additional information directly into the generated document using a robust, full-featured publishing tool. SoDA maintains consistency between your documents and the information in your software-engineering tools. With SoDA, you can produce higher-quality, more-useful documents with less time and effort.

SoDA also makes documents accessible to the users and maintainers of your system by putting them online and by providing hypertext traversal to the software-development tools that serve as information sources. These online navigational aids can be used to trace software requirements and to ensure that various lifecycle activities, such as analysis, design, coding, and testing, are consistent with one another.

SoDA provides full lifecycle support for your documentation.

Major capabilities

Supports automation throughout the lifecycle

SoDA works with all kinds of software-development tools (hereafter called information sources), such as programming environments or testing tools, to extract the relevant information from the internal data structures maintained by these tools. You can use SoDA to produce a wide variety of documents--such as requirements, design, testing, problem tracking, configuration management, and requirements traceability--that are relevant throughout the software-development lifecycle. By using the same documentation tool throughout your development cycle, you can cut your training and implementation costs while improving your documentation turnaround time.

Accommodates your choice of tools

While other tools for document automation are closely tied to one or more software-engineering tools, SoDA's client-server architecture enables you to extract information from any software-engineering tool. Usually, the integrations occur through application program interfaces (APIs). Each integration is known as a source domain. There is no limit to the number of tools with which SoDA can be integrated. Because SoDA works with any software-engineering tool, your investment will be protected even when you incorporate a new software-engineering tool or choose to drop an existing tool.

Allows you to use multiple sources of information to create a single document

SoDA can create a document from the information extracted from multiple information sources. There is no limit to the number of information sources you can use to create a document and no restriction on the kinds of information sources. For example, you can automatically create a document that takes information from an analysis and design tool, a programming environment, or your test-management and problem-tracking tools. You do not need to master separate document-generation tools specific to each separate software-development tool you may use. By extracting information from multiple sources to create a single document, SoDA provides a quick and efficient way to create any kind of document.

Checks consistency between documents and information

SoDA helps you keep your software documents synchronized with your software development by checking for consistency between the documents and the information sources. Using a single keystroke, you can navigate between a document section and the information source from which it is extracted, and you can make or review changes in the software tool and regenerate the document to reflect the changes in the information source. By keeping the documents consistent with the progress of your software development, SoDA ensures that you are getting a good return on your documentation-related investments.

Lets you customize document templates without programming

With SoDA, you can create a variety of document templates to support documentation needs throughout your organization. SoDA provides an easy-to-use, intuitive graphical user interface on top of a WYSIWYG editor for creating document templates. These document templates define the look-and-feel of the document, including formatting, structure, and style, as well as the mapping of document elements to the source repositories from which information is extracted.

Using SoDA, you can create document templates that conform to software documentation standards based on ISO 9000, IEEE, and DOD 2167A, or you can customize them to meet any of your internal documentation standards. SoDA comes with several precustomized templates. SoDA's WYSIWYG approach to customizing document templates eliminates the need for high-priced programming resources and further reduces cost and turnaround time.

Gives you Intelligent Document Merging(TM)

A key benefit of SoDA is the ability to repeat the process of document generation any number of times without losing the supplemental information that was manually entered into the document. SoDA preserves this information from generation to generation and keeps it consistent with the information extracted from the information sources. SoDA protects your investment in the document-preparation phase by preserving the manually entered data and keeping it consistent with the data extracted from engineering tools. It also substantially reduces the document-review cycle.

Allows you to incrementally generate and regenerate documents

For large, complex software systems, software documents can range from hundreds to thousands of pages. The documents must be continuously updated as the software evolves to reflect changes in the software. SoDA makes this process very efficient by allowing you to incrementally update only the portions of documents that are affected by changes to the software. Consequently, SoDA's incremental regeneration capability significantly improves turnaround time for document generation while lowering your computing resource burden.

Provides state-of-the-art publishing features

SoDA is built on FrameBuilder, a state-of-the-art publishing tool. You can enter additional information, such as text and graphics, using FrameBuilder's powerful features for creating, editing, and publishing structured documents. Moreover, FrameBuilder's guided editing helps you comply with your documentation standards and produce more consistent and maintainable documents. FrameBuilder also provides features, such as change bars, to help you see how one generation of a document differs from another. SoDA, bundled with FrameBuilder, saves you money while offering you a full range of publishing capabilities. SoDA can also support delivery of your final document in Interleaf format.

SoDA incorporates a high degree of automation and
flexibility for streamlining your software documentation.

Provides support for requirements traceability

SoDA gives you useful and easy-to-use mechanisms for tracking your software-development progress to ensure that requirements are being satisfied. SoDA can generate requirements traceability tables that show which design capabilities satisfy which requirements and which test cases test which requirements. By maintaining hypertext links between different software-lifecycle documents, SoDA helps you navigate online from requirements to analysis, design, coding, and testing of your software-development process. SoDA helps you save time and money in keeping track of requirements, without requiring you to buy additional, expensive requirements-management tools.

SoDA provides support for requirements traceability.

How does SoDA work?

Using SoDA's graphical user interface, which understands source tools, you first specify mapping between document structure and information sources. SoDA then automatically generates documents by extracting relevant data from the information sources. Using the publishing tool, you can enter supplemental information that will be preserved in future versions as documents evolve with the engineering information. SoDA allows you not only to move easily between documents and information sources to review or make changes but also to regenerate documents to reflect the changes.

SoDA provides unique value

SoDA automates the routine, tedious, and error-prone tasks of extracting information from your software-development tools, allowing you to concentrate on creative activities, such as describing the relationships between components of the system using additional text and graphics. All together, SoDA provides efficient automation while preserving the flexibility of manually produced documents.

SoDA extracts information from software-engineering tools at a fine granularity to populate document sections.

SoDA's product configuration

SoDA includes a base SoDA product and a choice of SoDA source integration domains. The base product contains the core SoDA functionality (information extraction and document generation) and comes bundled with FrameBuilder's prebuilt document masters. The source domains integrate SoDA with software-engineering tools such as programming environments and testing tools.

Build-on-demand capabilities

SoDA can be integrated with a variety of software-engineering tools, as long as those tools provide an API.

SoDA comes with certain standard information source domains. If you need other domains, Rational Software Corporation can build additional source domains on demand. We will work with you to define the integration requirements, and we will be responsible for developing and maintaining the new domains.